//
//  SFCLineConsumer.h
//  SVNForCocoa
//
//  Created by Jeremy Pereira on 13/12/2013.
//  Copyright (c) 2013 Jeremy Pereira. All rights reserved.
//
/*!
 *    @file
 *    @brief Declarations associated with the SFCLineConsumer class.
 */

#import <Foundation/Foundation.h>

@protocol SFCLineConsumer;

/*!
 *    @brief Thing that generates lines.
 */
@protocol SFCLineGenerator <NSObject>
/*!
 *    @brief The consumer of lines from this generator.
 */
@property (nonatomic, weak) id<SFCLineConsumer> consumer;
/*!
 *    @brief Line number that we are currently parsing.
 */
@property (nonatomic, readonly, assign) size_t lineNumber;

@end
/*!
 *    @brief A consumer of lines.
 *
 *    An object implementing this protocol consumes lines, possibly doing 
 *    something with them.  Id something goes wrong, the invoker can be notified.
 */
@protocol SFCLineConsumer <NSObject>

/*!
 *    @brief Consume a line.
 *
 *    The object does something with the line and returns a status to say if it 
 *    was successful.  It can also tell the invoker if it should consider the 
 *    line dealt with or if we didn't do anything with it.
 *
 *    @param generator  The thing that generates the lines
 *    @param line       The line of text to consume.
 *    @param isConsumed If true, it means we consumed the line, if false, we 
 *                      ignored it.  This is guaranteed to be a valid pointer
 *                      by the generator.
 *    @param error      If non nil and an error occurs, will be filled in with 
 *                      the error.
 *
 *    @return true if we successfully consumed or ignored the line.
 */
-(bool) generator: (id<SFCLineGenerator>) generator
      consumeLine: (NSString*) line
       isConsumed: (bool*) isConsumed
            error: (NSError* __autoreleasing*) error;
/*!
 *    @brief Called when the generator reaches the end of its stream/file.
 *
 *    This is called when all lines have been consumed and there is nothing left
 *    to do.
 *
 *    @param generator  The thing that generates the lines.
 *    @param isConsumed If true, it means we have consumed the end of file. If 
 *                      false, the generator will send it again.  This allows 
 *                      us to unwind a stack of consumers sending EOF to each 
 *                      consumer.
 *    @param error      If non nil and an error occurs, will be filled in with
 *                      the error.
 *
 *    @return true if processed successfully.
 */
-(bool) generator: (id<SFCLineGenerator>) generator
consumeEOFisConsumed:(bool *)isConsumed
            error:(NSError *__autoreleasing *)error;

@end
